前言：規則寫給 AI 看，但寫在哪裡才有用？

「這條規則我明明寫在專案文件裡了，AI 怎麼還是沒套用？」

如果你也遇過這種情況，問題往往不在「有沒有寫」，而在「寫在哪裡」。前面十五天講的都是「怎麼讓 AI 安全動手」——基準線、乾淨環境比對、Repository 分層、DI 容器陷阱。但這些規則本身要先被 AI「記住」,才有機會被套用。從今天開始進入第三部：焦點從「怎麼讓 AI 安全動手」轉向「怎麼讓 AI 記住這個專案的規矩、並且知道什麼時候該用哪一條」。

今日目標

• 理解「把所有規則塞進一份文件」為什麼會失效
• 認識 CLAUDE.md 跟 skill 各自該放什麼、不該放什麼
• 看懂這個分層背後真正要解決的問題：權重稀釋跟載入成本
• 建立「按需載入」這個判斷框架，作為之後幾天記憶系統的基礎

一份文件塞不下所有規則

一開始很容易犯一個直覺上的錯：把所有踩過的坑、所有該遵守的慣例，全部寫進同一份專案說明文件裡。這份文件會越長越大——分支策略、覆蓋率門檻、Repository 命名慣例、某個特定廠商的接線細節、某段 legacy 程式碼的已知陷阱……全部混在一起。

這樣做有兩個問題疊在一起。第一個是權重稀釋：當一份文件塞進幾百條規則，每一條在 AI 眼裡的份量都會被拉低，真正關鍵、幾乎每次都要遵守的規則，反而被淹沒在一堆只有特定情境才用得到的細節裡。第二個是載入成本：不管這次任務碰不碰得到某個特定廠商的接線細節，AI 每次都要把整份文件讀完，才能知道有沒有相關規則——這個成本會隨著文件變大而線性增加，而大部分時候讀進去的內容根本用不到。

分層的邏輯：什麼放 CLAUDE.md，什麼放 skill

解法是把規則按照「使用頻率」分兩層:

• CLAUDE.md 放全站規範：幾乎每次任務都適用的東西——編碼慣例、commit 訊息格式、數值精度要求（就是 Day 15 講的 bcmath 規則）、去識別化這類跟具體任務內容無關、但每次動筆都要檢查的規矩。
• Skill 放特定情境才要套用的具體規則：只有真的碰到那個領域,才需要載入的細節——資料庫存取的具體慣例、某類外部 API 的接線細節、某個特定子系統的已知陷阱。這些規則透過觸發範圍限定，只有工作內容真的落在對應範圍時才被載入進 AI 的判斷脈絡。

用一組對照來看差異：

❌ 全部塞進一份 CLAUDE.md：
# CLAUDE.md（800 行）
...
- 修改 Repository 時，findWhere() 的條件陣列要這樣寫...
- 呼叫外部 API 時，某個特定廠商的認證機制是...
- 某段 legacy 程式碼裡有個已知的日期格式陷阱...
...
→ 不管這次任務碰不碰得到 Repository、外部 API、那段 legacy 程式碼，
  AI 每次都要讀完全部 800 行，才知道有沒有相關規則
  真正每次都適用的規則（例如 bcmath），份量被淹沒在細節裡

✅ 分層：CLAUDE.md 精簡，細節按需載入
# CLAUDE.md（60 行）
- 金額運算一律用 bcmath
- commit 訊息用 Conventional Commits
...

# .claude/skills/repository-pattern/SKILL.md
（只有動到 Repository 相關程式碼時才載入）

# .claude/skills/vendor-integration/SKILL.md
（只有碰到外部 API 接線時才載入）
→ CLAUDE.md 本身份量小、每一條規則的權重都清楚；
  細節規則只在真的用得到的時候才進入判斷脈絡

這個分層要解決的不是「規則寫得夠不夠完整」，而是「AI 在每一個當下，判斷脈絡裡裝的是不是真正相關的東西」——跟 Day 04 講的覆蓋率門檻是同一種思路：不是要求 AI 記住更多，而是把它需要同時處理的範圍收斂到跟當下任務真正相關的邊界。

這也是 Day 01 主題句的另一種樣貌

如果 CLAUDE.md 塞了 800 行,AI 在執行一個只碰 Repository 的小任務時,「已經讀過專案規範」這件事,聽起來像是完整查證過,但實際上它可能因為份量太大、權重被稀釋，而漏掉某條真正該套用在這次任務上的規則——這正是 Day 01 那句話的另一種樣貌：AI 給出的「已確認遵守專案規範」這個結論，如果查證的方式是「囫圇吞棗讀完一份過長的文件」，這個查證本身的可靠度就已經打了折扣。按需載入的 skill,讓「這次任務真正相關的規則」變成一個可以被明確界定的範圍，而不是指望 AI 從一份大雜燴裡準確挑出重點。

今日思考題

回想你維護的專案裡，有沒有一份規範文件已經長到你自己都記不清楚裡面寫了什麼？如果把它拆成「幾乎每次都用得到」跟「特定情境才用得到」兩類，會不會拆出一份更精簡、也更容易被真正遵守的核心文件？

今日重點回顧

• 把所有規則塞進一份文件會造成兩個問題：權重稀釋、每次都要付出的載入成本
• CLAUDE.md 放全站規範，幾乎每次任務都適用；skill 放特定情境才要套用的具體規則，按需載入
• 這個分層的目標不是規則寫得夠不夠完整，而是 AI 當下的判斷脈絡裡裝的是不是真正相關的東西
• 這也是系列主題句的延伸：查證範圍如果被稀釋在過長的文件裡，查證本身的可靠度就會打折

明日預告

明天要更具體地看 skill 是怎麼被寫出來的——一個 skill 從哪裡來？往往不是憑空設計出一套規則，而是把一次真實踩過的坑，提煉成一份下次可以直接套用的流程。